Quarto

Postgrau d’Analista de Dades (UB)

Jordi Mas Elias

https://www.jordimas.cat/

Sumari

  1. Què és Quarto?
  2. Repàs primeres sessions
  3. Tutorial Quarto
  4. Quarto avançat
  5. Consideracions finals

1. Què és Quarto?

Orígens: Markdown

“A Markdown-formatted document should be publishable as-is, as plain text, without looking like it’s been marked up with tags or formatting instructions”

Illustration of three species of Palmer Archipelago penguins: Chinstrap, Gentoo, and Adelie. Artwork by @allison_horst.

  • John Gruber, 2004.
  • Un format més fàcil de llegir i d’escriure que la majoria de llenguatges web com l’Html.
  • Convertible fàcilment a Html, Pdf…

Orígens: RMarkdown

  • S’adopta a RStudio.
  • Permet alternar codi d’R amb text.
  • Fàcilment exportable a varis formats
  • Exemples:

Orígens: RMarkdown

Crear un document: YAML - Text - Chunk

Document Quarto.

Orígens: Quarto

Quarto

Posit

2. Repàs primeres sessions

RStudio

  • Crear projecte
  • Diferència entre instal·lar i carregar paquets
  • Utilitzar l’Environment
  • Importar arxius: csv, csv2, xlsx, dta, sav…

Quarto

Crear un document: YAML - Text - Chunk

RMarkdown logo.

Descarregar tutorial

https://www.jordimas.cat/files/Tutorial_Qmd_Polity.zip

3. Tutorial Quarto

Configurar Quarto

  • YAML - Text - Chunk
  • Render: Ctrl + Shift + K
  • Visualització: Preview in Viewer Pane
  • Output: Chunk Output in Console

YAML

  • Què és?
  • Nom, títol i data.
  • ---

Exercici 1: YAML

Provar amb:

format: 
  html:
    theme: cosmo

Text

  • Negreta, cursives, codi, enllaços, nota al peu1.

  • Seccions (#) i subseccions (##)

  • Ítems i subítems.

  • Ítems enumerats.

Exercici 2: Text

Llegir introducció i fins a la imatge de Quarto. Fer els canvis que es proposen en el text.

Chunks

  • Què és? Ctrl + Alt + I
  • Inici i final d’un chunk.
  • Etiquetes del chunk.
  • Elements: echo, eval, message, warning.

Exercici 3: Chunks

Llegir fins a l’apartat Imatges i gràfics i fer canvis que es proposen.

Taules, imatges i gràfics

  • Posem aquests elements a dins del chunk.
  • Marc de dades: tibble, kable1, datatable.
  • Imatges: ![]() o include_graphics("__").
  • Gràfics: fig.align = "center".

Exercici 4: Dades i gràfics

Llegir l’últim apartat, modifica marc de dades i gràfic.

Avís important

És important diferenciar entre

  • Mode Render: Llegeix el document Quarto de dalt a baix.
  • Mode R Script: Utilitzem el que tenim guardat/carregat al Global Environment.

Activitat

Exercici 5: Polity V

Crear una petita història amb Polity V:

  • Descarregar la base de dades sencera de Polity V a Systemic Peace
  • Text amb tots els formats possibles.
  • Un marc de dades i dos plots.

4. Quarto avançat I

Important!!!!

Guia de Quarto

4.1. Quarto avançat (YAML)

Propietats del document

Data automàtica.

date: "`r Sys.Date()`"
[1] "2024-10-10"

Canviar l’idioma de la capçalera.

author-title: Autor
published-title: Última modificació
lang: ca

Integrar els recursos a l’Html.

format: 
  html:
    embed-resources: true

Foto d’encapçalament

Posem una foto a la capçalera del document1.

subtitle: "Posar subtítol si s'escau![](polity-index.jpeg){width=30%}"

Taula de continguts

Customitzem elements de la taula de continguts.

format: 
  html:
    toc: true
    toc-depth: 2
    toc-title: Taula de continguts

Canviar la mida de tot el text

Un dels deutes pendents de Markdown1.

fontsize: 18px
mainfont: Arial

Plegar codi

Creem un desplegable per cada chunk amb codi (echo = T) que tinguem al document1.

format:
  html:
    code-fold: true
    code-summary: "Mostrar codi."

Temes

Seleccionem l’estil visual i el subratllat:

  • Tema: default, cerulean, cosmo, cyborg, darkly, flatly, journal, litera, lumen, lux, vapor, null.
theme: journal
  • Highlight: a11y, arrow, atom-one, ayu, breeze, github, gruvbox.
highlight-style: ayu

Formats d’output

Al YAML podem especificar el tipus de format1.

format:
  pdf:
    toc: true
    number-sections: true
    colorlinks: true

I també podem crear diapositives en diversos formats.

4.2. Quarto avançat (text)

Referències al text

Per referenciar la secció del document1:

# Introducció {#intro}

En qualsevol moment del text, introduïm:

[text](#intro)

Referències bibliogràfiques

Ho farem normalment amb un document BibTex (.bib)1.

  1. Obrim un Text file, el guardem com a biblio.bib i introduïm:
@misc{Marshall2020,
author = {Marshall, Monty G. and Gurr, Ted Robert},
publisher = {Center for Systemic Peace},
title = {{Polity V. Political Regime Characteristics and Transitions, 1800-2018}},
year = {2020}
}
  1. Indiquem al YAML on es troba l’arxiu:
bibliography: biblio.bib
  1. Citem les referències al text.
  • Entre claudàtors [@Marshall2020], ens posarà (Marshall 2020).
  • Sense claudàtors @Marshall2020, ens posarà Marshall (2020).
  1. En l’última línia del document de Quarto, posarem un títol # Referències per separar la bibliografia de la resta del text.

Taules

Una assignatura pendent de Markdown.

    | Funció       | Paquet    | Descripció                                           |
    |--------------|-----------|------------------------------------------------------|
    | `filter()`   | `dplyr`   | Filtra les observacions d'un marc de dades           |
    | `separate()` | `tidyr`   | Separa els elements d'un vector en base a un criteri |
    | `read_csv()` | `readr`   | Llegeix els arxius CSV                               |
    | `ggplot()`   | `ggplot2` | Reprodueix elements gràfics                          |
Funció Paquet Descripció
filter() dplyr Filtra les observacions d’un marc de dades
separate() tidyr Separa els elements d’un vector en base a un criteri
read_csv() readr Llegeix els arxius CSV
ggplot() ggplot2 Reprodueix elements gràfics

També podem utilitzar l’Editor Visual (següent).

Editor visual

Interfície més semblant a Word per generar documents.

Amb l’editor visual veurem una interfície que ens serà molt més familiar. No obstant, recomanem utilitzar-lo només puntualment.

4.3. Quarto avançat (chunks)

Opcions globals

Opcions per defecte als chunks de tot el document:

knitr::opts_chunk$set(fig.align = "center", echo = TRUE,
                      warning = FALSE, message = FALSE,
                       fig.width = 6, fig.height = 6)

El primer chunk també és útil per carregar els paquets i objectes que necessitarem.

Figures

Varis paràmetres per establir les dimensions1:

  • fig.width: amplada en inches.
  • fig.height: alçada en inches.
  • fig.align: “left”, “right”, “center”.
  • fig.dim: primer width i després height, c(5,3)

Millorar les taules

Tot tipus de taules amb el paquet KableExtra

polity |> 
  filter(country %in% c("Angola", "Spain", "Vietnam"),
         year == 2014) |> 
  select(country, scode, polity2, durable) |> 
  knitr::kable()

Arguments d’interès:

polity |> 
  select(country, scode, polity2, durable) |> 
  DT::datatable()

Què evitar als chunks

  • La funció install.packages().
  • La funció download.file().
  • La funció View().
  • Carregar bases de dades d’internet.
  • Funcions que carreguen bases de dades (ex. CEOdata)

4.4. Quarto avançat (publicar)

Exportar i publicar

Podem publicar documents Html, entre altres, amb Quarto Pubs:

Activitat

Exercici 7: Prova final

Proveu un dataset anterior i construiu de zero un document Quarto amb Html, procurant d’utilitzar també algunes de les funcions avançades. En particular:

  • Marc de dades en knitr o DT.
  • Temes i subratllats.
  • Plegar codi.
  • Mida gràfics.

5. Quarto avançat II

5.1. Quarto avançat (YAML)

Gràfics per defecte

Els gràfics que apareixen al document han de tenir per defecte algunes dimensions determinades?

format: 
  html:
    fig_width: 6 
    fig_height: 4

Paràmetres

Establim uns paràmetres al YAML que al llarg del document podrem utilitzar com a codi 1.

params:
  country: "United States"
  year: 2014

5.2. Quarto avançat (text)

Incloure codi al text

En qualsevol moment, al text podem referenciar qualsevol dada ja carregada en un chunk previ.

  • A. Carreguem les dades:
polity <- read_excel("../data/p5v2018.xls")
  • B. Per referenciar al text:
`r data`

Estats Units en els darrers anys.

p5_ctr <- polity |> 
  filter(country == "United States", year > 2012) |> 
  select(country, year, polity2)

Observem que:

  • En l’últim any de dades …
`r last(p5_ctr$year)`
  • el país …
`r p5_ctr$country[1]`
  • tenia un nivell de democràcia de …
`r last(p5_ctr$year)`
polity |> 
  group_by(country) |> 
  summarize(duration = max(durable, na.rm = T)) |> 
  ggplot(aes(x = duration)) +
  geom_density()

El règim amb més durada és …

`r polity$country[which(polity$durable == max(polity$durable, na.rm = T))]`

que ha durat X anys:

max(polity$durable, na.rm = T)

Tabsets

::: {.panel-tabset}

## Tab A

Contingut de `Tab A`

## Tab B

Contingut de `Tab B`

:::

Quadres de text

Avís!

Utilitzar quadres de text és una manera efectiva per dirigir l’atenció a determinat contingut.

::: {.callout-note}
## Títol
Text blablabla
:::

Tipus:

  • note, tip, warning, caution, important.

5.3. Quarto avançat (chunk)

Incrustar vídeos i tuits

{{< video https://www.youtube.com/embed/hz3J6Wb5S_8 >}}
{{< tweet 1229386394658836480 >}}

6. Consideracions finals

Interactius

leaflet() %>% 
  addProviderTiles(providers$Stamen.Toner) %>%
    setView(lng = 139.753930, 
          lat = 35.682170, 
          zoom = 13)

Bibliografia principal

Quarto - Postgrau d’Analista de Dades (UB)